home *** CD-ROM | disk | FTP | other *** search
/ Amiga Format CD 41 / Amiga Format CD41 (1999-06)(Future Publishing)(GB)[!][issue 1999-07].iso / -seriously_amiga- / misc / vinced / include / boopsis_readme next >
Text File  |  1999-04-19  |  7KB  |  173 lines
  1. Starting with release 3.53, ViNCEd gadgets can be customized. This is no 
  2. longer restricted to the system standard gadgets, the ViNCEd iconify gadget
  3. and the title bar buttons can be customized as well. Moreover, if you write
  4. your own application, you may use these gadgets as well - this makes your
  5. GUI freely designable by the user.
  6.  
  7.  
  8. If you want to write a "GUI improver" software....
  9. --------------------------------------------------
  10.  
  11. ...you should supply two public "Boopsi Classes" called
  12. "tbiclass". The class should be a subclass of the ordinary "image" 
  13. class and will be allocated by ViNCEd for the iconify gadget and 
  14. the "title bar" gadgets. The image class should come in at least
  15. two "flavours", determinated with the "SYSIA_Which" tag. This tag
  16. is defined in "intuition/imageclass.h".
  17.  
  18.  
  19. Details about the iconify image flavour of the "tbiclass"
  20. ---------------------------------------------------------
  21.  
  22. This image subclass is used to render the iconify gadget in ViNCEd and
  23. other windows.
  24.  
  25. You receive the following information thru the standard tag items:
  26.  
  27. SYSIA_Which    with a tag value of 104, defining the "iconify flavour".
  28.  
  29. Width & height of the image to create. These values will be the dimensions
  30. of the "depth arrangement" gadgets in the window. You may well ignore these
  31. parameters as long as the specified dimensions alter by the returned 
  32. dimensions by a reasonable amount - meaning: screen sized gadgets won't 
  33. work, but everything that fits in the titlebar should. ViNCEd tries to adjust 
  34. its GUI accordingly to make enough room for your image.
  35.  
  36. The DrawInfo of the screen the window is to be created on. You should use it
  37. to choose the correct pens for your image.
  38.  
  39. ViNCEd will allocate only ONE instance of this boopsi class and use it for
  40. both, the regular and the hilited image of the iconify gadget. Make sure
  41. your boopsi class is smart enough to render itself accordingly, you receive
  42. all necessary information thru the standard boopsi "message".
  43.  
  44. You WILL NOT receive a recessed/raised flag of the image to create. As I
  45. said, your boopsi class is expected to be smart enough.
  46.  
  47. To be compatible to an intuition "feature", ViNCEd expects that the LeftEdge
  48. of your returned image is set to "-1", hence, the image is shifted by one
  49. pixel to the left relatively to the gadget. This sounds a bit strange, but
  50. intuition treads the standard system images in quite the same way. The reason
  51. for this displacement of the image is to keep the left black image border out
  52. of the sensitive area of the gadget. This dark border appears later on to be
  53. the apparent right border of the title bar.
  54.  
  55.  
  56. Details about the button flavour of the "tbiclass"
  57. --------------------------------------------------
  58.  
  59. This image subclass is used to render the "titlebar buttons" of ViNCEd 
  60. windows.
  61.  
  62. You receive the following tags:
  63.  
  64. SYSIA_Which    with a tag value of 106, defining the "button flavour".
  65.  
  66. Width & height of the image to create. You may well ignore the height
  67. parameter as long as you make sure your image will be the same size as the
  68. title bar of the window. You ABSOLUTELY MUST obey the width parameter, ViNCEd
  69. relies on the correct value set in the boopsi returned.
  70.  
  71. The DrawInfo of the screen for rendering informations.
  72.  
  73. You WILL NOT receive a recessed/raised flag for the image to create. As above,
  74. ViNCEd expects that your image class is smart enough to render itself
  75. accordingly, all necessary data can be received from intuition. 
  76.  
  77. ViNCEd will allocate only ONE instance of this boopsi per button, and will
  78. use it for both, the gadget image and the hilite image - the pointer goes
  79. to the "GadgetRender" and "SelectRender" fields of the gadgets.
  80.  
  81. Expect that parts of your images will be obscured by text, the contents of
  82. the button.
  83.  
  84. To be compatible with a feature of intuition, ViNCEd expects that the image
  85. is shifted to the left by one pixel, i.e. the LeftEdge entry of the image
  86. structure must be set to -1. See above for details.
  87.  
  88.  
  89.  
  90. If you write your own application and need an iconify gadget or a title bar
  91. button...
  92. ----------------------------------------------------------------------------
  93.  
  94. First, provide your own standard gadget imagery. Make sure your program
  95. works on a plain system, without any "GUI improver" software. If you want
  96. your gadgets to get standard images, try the following to get a standard
  97. iconify gadget:
  98.  
  99.  
  100. Allocate a boopsi of the public "tbiclass" class, 
  101. provide the following tags:
  102.  
  103. SYSIA_Which    with a tag value of 104, defining the "iconify flavour".
  104.  
  105. Width & height, and the DrawInfo of the screen your window is located on.
  106.  
  107. If this allocation fails, fall back to your own image. 
  108.  
  109. If it works:
  110.  
  111. Check the width and the height of the returned image. They might be different
  112. from your specifications in order to give a "better look". Adjust your GUI
  113. accordingly, make some room for this image. Fill the pointer you received
  114. in the "GadgetRender" and "SelectRender" fields of the gadget structure
  115. and specify alternate images as gadget rendering mechanisms. MAKE SURE
  116. YOU ADJUST THE GADGET SIZE to reflect the dimensions of the image!
  117.  
  118. To be compatible to an intuition feature, the image you receive will be 
  119. shifted to one pixel to the left. DO NOT ALTER the image structure you
  120. received, it isn't yours! Move the gadget instead if you need to do so!
  121. Read the paragraph above for more details.
  122.  
  123.  
  124.  
  125. If you need a standard button in your title bar:
  126.  
  127. Allocate a boopsi of the "tbiclass", provide the following tags:
  128.  
  129. SYSIA_Which    with a tag value of 106, defining the "button flavour".
  130.  
  131. Width & height of the button you need. The "width" can be as big as you like,
  132. but the height should be the height of the title bar of the window. If the
  133. window is not yet open, specify a reasonable value, it will be adjusted
  134. for you.
  135. DrawInfo of the screen your window is located on. THIS TAG is ABSOLUTELY 
  136. NEEDED! 
  137.  
  138. You receive either NULL if the class isn't available. Fall back to your own
  139. image or border if you get this as result. If you don't get NULL, you're
  140. holding one instance of an image-like boopsi. It's width is guaranteed to
  141. be the width you specified, but the height might differ to adjust the image
  142. in the title bar. Set the "GadgetRender" and "SelectRender" fields of an
  143. intuition gadget to this pointer and specify images as regular and selected
  144. rendering of the gadget. MAKE SURE YOU ADJUST THE GADGET HEIGHT to reflect
  145. possible changes.
  146.  
  147. To be compatible with an intuition feature, this image will be shifted
  148. leftwards by one pixel. This will move the 3D-look border of it out of
  149. the gadget activation region and is an intuition feature. Please DO NOT
  150. adjust the image structure yourself, it isn't yours. Move the gadget
  151. instead if you have to.
  152.  
  153. _____________________________________________________________________________
  154.  
  155. The following programs are tested and support both image classes:
  156.  
  157. Visual Prefs by Massimo Tantignone.
  158.  
  159.  
  160. The following programs use the image classes:
  161.  
  162. ViNCEd
  163.  
  164. _____________________________________________________________________________
  165.  
  166. For further questions, contact me at
  167.  
  168.     thor@math.tu-berlin.de
  169.  
  170.  
  171. So long,
  172.     Thomas Richter,        August 1998
  173.